Skip to content

PORT-14552 - Docs for Github ocean integration #2494

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 201 commits into
base: main
Choose a base branch
from

Conversation

melodyogonna
Copy link
Contributor

Description

This is the initial docs for the new Github integration powered by Ocean framework.

Added docs pages

  • Github Ocean (/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/)
  • Installation (/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation)
  • Self-hosted app installation (/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/self-hosted-installation)
  • Examples (/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/resource-mapping-examples)

@mk-armah mk-armah requested review from shariff-6 and oiadebayo July 1, 2025 14:40
Copy link

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2494.d2ngvl90zqbob8.amplifyapp.com

@melodyogonna melodyogonna marked this pull request as ready for review July 1, 2025 19:47
Comment on lines 27 to 41
:::info repository type

The `repositoryType` parameter filters which repositories are ingested. It corresponds to the `type` parameter in GitHub's [List organization repositories](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-organization-repositories) API.

<details>
<summary>Possible values:</summary>

* `all` (default): All repositories accessible to the provided token.
* `public`: Public repositories.
* `private`: Private repositories.
* `forks`: Only forked repositories.
* `sources`: Only non-forked repositories.
</details>

:::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please move this to be inside the appConfig collapsible, currently it is not very clear what it refers to.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @hadar-co where do I find more information about this appConfig? My searches don't seem to turn up any useful information.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i meant the snippet that follows right after the callout. I remember that it had this repositoryType param, but now i see that it doesnt. Did you remove it intentionally?
In my comment I meant that it makes sense to explain what repositoryType is in the same place where it appears, so there's context.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I get you now. I moved it to the integration home page as part of the configuration documentation can you check it out? I initially had it in the examples app config, it did not look very nice.

import PortApiRegionTip from "/docs/generalTemplates/\_port_region_parameter_explanation_template.md"
import InstallMethods from "./\_install_methods.mdx"

# Github App
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we need another page for installing the github app? why not use the existing docs?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a custom app installation
The user creates a custom app with permissions which is later re-configured by the integration itself.

The existing github app installation is just setting up the monorepo's installation
@melodyogonna @emekanwaoma correct me if im wrong

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hadar-co it has steps (and images) on how to create the app rather than just how to install it. I felt it warranted another page.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@matan84 @melodyogonna
I see, so the installation/configuration is different from the regular app? If so, let's clarify that this is a custom app with some manual configuration

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is similar to the Github app setup documented here for the existing Github Cloud App: https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/github/self-hosted-installation

Except a few steps in the setup are removed, and the deployment is expanded.

Copy link
Member

@matan84 matan84 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a few recommendations

- Only JSON and YAML formats are automatically parsed.
Other file formats can be ingested as raw files, however, some special characters in the file (such as `\n`) may be processed and not preserved.

## Permissions
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's put it as one of the first if not the first paragraph of the integration page

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hadar-co Also would love your opinion here

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@matan84 I'm not sure I understand, should I move the capabilities example further up the page? This is part of a larger content.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@matan84 you're talking about the permissions header, right? If so, perhaps we can call it "Prerequisites" instead and move it to be before "Setup". WDYT?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like calling it prerequisites and putting it above Setup

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hadar-co I'm wondering if this isn't redundant information, there is a required permissions in the installation page as well, I think that is a much better place to have it. My instinct is to remove this entirely.

@melodyogonna melodyogonna force-pushed the PORT-14552-document-github-ocean branch from 0eee868 to 59ccbd2 Compare July 23, 2025 15:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants